<HTML><HEAD><TITLE>findall(?Term, +Goal, -List)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">All Solutions</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>findall(?Term, +Goal, -List)</H1>
List is the (possibly empty) list of all instances of Term such that Goal
is provable.


<DL>
<DT><EM>Term</EM></DT>
<DD>Prolog term, usually a variable, a compound term or list                containing variables.
</DD>
<DT><EM>Goal</EM></DT>
<DD>Callable term.
</DD>
<DT><EM>List</EM></DT>
<DD>List or variable.
</DD>
</DL>
<H2>Description</H2>
   Unifies List with the list (not ordered, duplicates retained, no choice
   point) of all instances of Term such that Goal is satisfied.  The
   variables appearing in Term should not appear anywhere else in the
   clause except within Goal.

<P>
   The following table illustrates the difference between the all solutions
   predicates:

<P>
<PRE>
    built-in  choice pts  duplicates  sorted pruned *
    bagof/3   yes         yes         no     no
    coverof/3 yes         no          no     yes
    findall/3 no          yes         no     no
    setof/3   yes         no          yes    no
   * prune_instances/2 used on list of solutions.
</PRE>
   If Goal is not a callable term, exceptions are raised in call/2.

<P>
Note

<P>
 1. Even if there are uninstantiated variables in Goal which do not appear
    in Term, then unlike bagof/3, findall/3 has no choice points i.e.
    these variables are taken to be existentially quantified.

<P>
 2. findall/3 never fails; if no solution exists, the empty list is
    returned.

<P>

<H3>Modes and Determinism</H3><UL>
<LI>findall(?, +, -) is det
</UL>
<H3>Modules</H3>
This predicate is sensitive to its module context (tool predicate, see @/2).
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>Goal is not instantiated.
<DT><EM>(5) type error </EM>
<DD>Goal is instantiated, but not to a compound term.
<DT><EM>(68) calling an undefined procedure </EM>
<DD>Goal is an undefined procedure.
</DL>
<H2>Examples</H2>
<PRE>
Success:


   % all variables are taken to be existentially quantified:
  [eclipse]: findall(Name,current_stream(Name,Mode,Num),L),
  &gt; writeq((Name,Mode,Num,L)), nl, fail.
  _g72 , _g78 , _g84 , [user, user, error, debug_input, null, ""]
  no (more) solution.

  [eclipse]: [user].
   h(f(1,2)).
   h(f(1,2)).
   h(f(1,X)).
   h(f(X,Y)).   % instances of this element...
   user compiled 476 bytes in 0.00 seconds
  yes.
  [eclipse]: findall(X,h(X),L).
  X = _g58
  L = [f(1, 2), f(1,2), f(1, _g116), f(_g100, _g102)]
  yes.  % ...all bagged; includes duplicates.

  [eclipse]: findall(X,current_built_in(X),L).
  X = _g58
  L = [findall/3, !/0, delayed_goals/1, delayed_goals/2,
  '.'/2, (;)/2, (&lt;)/2, (;)/4, (;)/5, error/2, error/3,
  (',')/2, (',')/4, close_window/0, (=)/2, op/3, (&gt;)/2,
  array/3, (spied)/1, ... / ..., ...]
  yes.

  [eclipse]: findall(X,append_strings(X,Y,"abc"),L).
  X = _g58
  Y = _g66
  L = ["", "a", "ab", "abc"]

Fail:
  findall(Y,current_stream(X,Y,Z),[strin]).

Error:
  findall(X,G,L).         (Error 4).
  findall(X,"G",L).       (Error 5).
  findall(X,a,L).         (Error 68).
  findall(X,a(X),L).      (Error 68).



</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/allsols/bagof-3.html">bagof / 3</A>, <A HREF="../../kernel/allsols/coverof-3.html">coverof / 3</A>, <A HREF="../../kernel/allsols/setof-3.html">setof / 3</A>
</BODY></HTML>
